home *** CD-ROM | disk | FTP | other *** search
/ The Arsenal Files 2 / The Arsenal Files 2 (Arsenal Computer).ISO / os2 / pgmg20c1.exe / PGMGC1.ZIP / DOC / README.PRG
Encoding:
Text File  |  1994-06-13  |  12.8 KB  |  429 lines
  1.  
  2.   IBM TCP/IP Version 2.0 for OS/2 Programmer's Toolkit
  3.  
  4.      This README file reflects new and changed functions for
  5.      the TCP/IP 2.0 for OS/2: Programmer's Toolkit and
  6.      documents changes introduced in the original product
  7.      as well as changes due to Corrective Service Diskette
  8.      (CSD) UN54155.
  9.  
  10.      Note:  This TCP/IP kit has Corrective Service UN57887 and
  11.      UN54155 already applied.
  12.  
  13.  
  14.  
  15.   Contents of this README file include:
  16.  
  17.                -  Previous CSD Information
  18.                -  Obtaining CSDs
  19.                -  CSD UN57887 Contents
  20.                -  CSD UN54155 Contents
  21.                -  Fixed APARs
  22.  
  23.  
  24.                  *************************************
  25. *****************      Previous CSD Information       *******************
  26.                  *************************************
  27.  
  28.      This CSD incorporates the corrective service and new functions that
  29.      have been released in all available CSDs for TCP/IP Version 2.0
  30.      for OS/2.  This file contains information about all functions
  31.      described in the following CSDs:
  32.  
  33.           -  UN57887
  34.           -  UN54155
  35.  
  36.  
  37.  
  38.                  *************************************
  39.  ****************           Obtaining CSDs            *******************
  40.                  *************************************
  41.  
  42.   You can obtain Corrective Service Diskettes (CSDs)
  43.   electronically by:
  44.  
  45.   o Using FTP to access SOFTWARE.WATSON.IBM.COM as Anonymous.
  46.  
  47.     NOTE:  Fixes for TCP/IP for OS/2 are located in the
  48.            pub\tcpip\os2 directory.
  49.  
  50.   o Establishing a modem connection to the NCSBBS bulletin
  51.            board at 1-919-517-0001.
  52.  
  53.     NOTE:  Set your modem settings to: none,8,1.
  54.  
  55.   The latest CSDs for TCP/IP Version 2.0 for OS/2 are shown
  56.   in the following table:
  57.  
  58.   +----------------------------+---------------------------+
  59.   | KIT NAME                   | PACKAGE NAME              |
  60.   +----------------------------+---------------------------+
  61.   | Applications Kit           | APP20CSD.PKG              |
  62.   +----------------------------+---------------------------+
  63.   | Base Kit                   | TCP20CSD.PKG              |
  64.   +----------------------------+---------------------------+
  65.   | Domain Name Server Kit     | DNS20CSD.PKG              |
  66.   +----------------------------+---------------------------+
  67.   | DOS/Windows Access Kit     | DOS20CSD.PKG              |
  68.   +----------------------------+---------------------------+
  69.   | Extended Networking Kit    | XNT20CSD.PKG              |
  70.   +----------------------------+---------------------------+
  71.   | Network File System Kit    | NFS20CSD.PKG              |
  72.   +----------------------------+---------------------------+
  73.   | OSF/Motif Kit              | MOT20CSD.PKG              |
  74.   +----------------------------+---------------------------+
  75.   | Programmer's Toolkit       | PGM20CSD.PKG              |
  76.   +----------------------------+---------------------------+
  77.   | X Window System Client Kit | XCL20CSD.PKG              |
  78.   +----------------------------+---------------------------+
  79.   | X Window System Server Kit | PMX20CSD.PKG              |
  80.   +----------------------------+---------------------------+
  81.  
  82.  
  83.  
  84.                  *************************************
  85. ***************** UN57887 CORRECTIVE SERVICE DISKETTE *******************
  86.                  *************************************
  87.  
  88.    Topics included in CSD UN57887 are:
  89.  
  90.         1. Programming Support
  91.         1.1  REXX File Transfer Protocol API
  92.         1.2  REXX Socket Support
  93.         2. New FTP API Calls
  94.         2.1  ftptrcoff()   Stops tracing
  95.         2.2  ftptrcon()    Starts tracing
  96.         2.3  ftpver()      Returns the version number
  97.         3. Packet Size Restriction
  98.         4. Performance Considerations
  99.  
  100.   ----------------------------------------------------------------
  101.  
  102.  1  Programming Support
  103.  
  104.   The REXX File Transfer Protocol API and the REXX Socket
  105.   Support are included in the Base Kit CSD.
  106.  
  107.  
  108.  1.1  REXX File Transfer Protocol API
  109.  
  110.   The REXX File Transfer Protocol (FTP) Application Program
  111.   Interface (API) package provides access to the OS/2 TCP/IP FTP
  112.   API's.  It is assumed you are familiar with the basic FTP. The
  113.   REXX FTP API function names are similar to the FTP subcommands.
  114.  
  115.   For more information and installation instructions,
  116.   type:  view RXFTP   at an OS/2 command line after installing
  117.   the Base Kit CSD or select the REXX FTP API icon in the
  118.   TCP/IP folder.
  119.  
  120.  
  121.  1.2  REXX Socket Support
  122.  
  123.   The REXX Socket Support package provides access to the OS/2
  124.   TCP/IP socket API's.  It is assumed you are familiar with the
  125.   basic socket APIs and that you can reference the OS/2 specific
  126.   ones.  For more information and installation instructions,
  127.   type:  view RXSOCKET  at an OS/2 command line after installing
  128.   the Base Kit CSD or select the REXX Sockets API icon in the
  129.   TCP/IP folder.
  130.  
  131.   ----------------------------------------------------------------
  132.  
  133. 2.  New FTP API Calls
  134.  
  135.    ftptrcoff()      Stops tracing
  136.    ftptrcon()       Starts tracing
  137.    ftpver()         Returns the version number
  138.  
  139.  
  140. 2.1 >>>>>>>>>>>>>>>>>>> ftptrcoff() <<<<<<<<<<<<<<<<<<<
  141.  
  142. ftptrcoff() Call
  143.  
  144.  
  145. Syntax for ftptrcoff()
  146.  
  147.   #include <ftpapi.h>
  148.  
  149.   int ftptrcoff(void)
  150.  
  151.  
  152. Parameters
  153.  
  154.   none
  155.  
  156.  
  157. Return Values
  158.  
  159.   The ftptrcoff() always return a value of 0.
  160.  
  161.  
  162. Description
  163.  
  164.   The ftptrcoff() closes the trace file and stops
  165.   tracing of the command and reply sequences sent
  166.   over the control connection between the local
  167.   and remote hosts.
  168.  
  169.  
  170. Example
  171.  
  172.   int rc;
  173.   rc = ftptrcoff();
  174.  
  175.  
  176. 2.2 >>>>>>>>>>>>>>>>>>>> ftptrcon() <<<<<<<<<<<<<<<<<<<
  177.  
  178. ftptrcon() Call
  179.  
  180.  
  181. Syntax for ftptrcon()
  182.  
  183.   #include <ftpapi.h>
  184.  
  185.   int ftptrcon(fileSpec, mode)
  186.   char *fileSpec;
  187.   int mode;
  188.  
  189.  
  190. Parameters
  191.  
  192.   fileSpec  Identifies the name of the trace file.
  193.  
  194.   mode      Specifies the trace mode as overwrite or append.
  195.  
  196.             M_OVERLAY  -  trace data overwrites previous
  197.                           information
  198.  
  199.             M_APPEND   -  trace data appends to previous
  200.                           information
  201.  
  202.  
  203. Return Values
  204.  
  205.   There are three possible return values for ftptrcon():
  206.  
  207.     0 when successful
  208.  
  209.     TRCMODE indicates the value set into mode was invalid
  210.  
  211.     TRCOPEN indicates the trace file could not be opened
  212.  
  213.  
  214. Description
  215.  
  216.   The ftptrcon() call opens the trace file specified and
  217.   starts tracing of the command and reply sequences
  218.   sent over the control connection between the local
  219.   and remote hosts.  The trace file can be written
  220.   over or appended to.
  221.  
  222.   No notification is provided if writing of trace data
  223.   fails.
  224.  
  225.   Telnet command and reply sequences are not traced
  226.   nor are command and reply sequences between the
  227.   local host and a proxy host.
  228.  
  229.  
  230.  
  231. Example
  232.  
  233.   To write the trace data into a file named api.trc
  234.   in the C:\WORK directory, use:
  235.  
  236.  
  237.   int rc;
  238.   rc = ftptrcon("c\\work\\api.trc", M_OVERLAY);
  239.  
  240.  
  241.   If the file already existed, the new trace data
  242.   overwrites the previous trace data (overlay mode).
  243.  
  244. 2.3 >>>>>>>>>>>>>>>>>>>> ftpver() <<<<<<<<<<<<<<<<<<<
  245.  
  246. ftpver() Call
  247.  
  248.  
  249. Syntax for ftpver()
  250.  
  251.   #include <ftpapi.h>
  252.  
  253.   int ftpver(buf, buflen)
  254.   char *buf;
  255.   int buflen;
  256.  
  257.  
  258. Parameters
  259.  
  260.   buf     Identifies the buffer to store the version
  261.           string.
  262.  
  263.   buflen  Specifies the length of the buffer.
  264.  
  265.  
  266.  
  267. Return Values
  268.  
  269.    0  when successful
  270.  
  271.   -1  when the complete version string could not be
  272.       copied because the buffer length was too small.
  273.  
  274.  
  275. Description
  276.  
  277.   The ftpver() call stores the string containing the
  278.   FTP API version.  The string is truncated to fit into
  279.   the buffer if it is longer than the buffer length.
  280.   The returned string is always null-terminated.
  281.  
  282.  
  283. Example
  284.  
  285.   int rc;
  286.   rc = ftpver(verBuf, bufLen);
  287.  
  288.  
  289.   After the ftpver() call, the buffer contains the
  290.   following:  2.0.1
  291.  
  292.  
  293. 3. Packet Size Restriction
  294.  
  295.    The packet size for sending and receiving data is limited
  296.    to 32K of data.  When the data sent or received is
  297.    greater that 32K, the programmer must divide up the data
  298.    so that no packet exceeds 32K.
  299.  
  300.    This restriction applied to all socket calls.
  301.  
  302.    For example, to handle this restriction for the send()
  303.    function:
  304.  
  305.     int SendData(int socket, void *buffer, int len, int flags)
  306.     {
  307.       int rc;
  308.       char *temp    = (char *)buffer;
  309.       int  templen  = len;
  310.       int  errno    = 0;
  311.       do {
  312.          /* Never send more than 32K */
  313.          rc = send(socket, temp, min(templen,0xfff), flags);
  314.          if(rc > 0) {
  315.            temp     += rc;
  316.            templen  -= rc;
  317.          } /* endif */
  318.       } while (rc > 0) && templen); /*enddo */
  319.  
  320.       if(templen) {                    /* If there is still data, then  */
  321.         if(rc) errno = -sock_errno();  /*  1. there was an error        */
  322.         else   errno = EPIPE;          /*  2. the connection was closed */
  323.       } /* endif */
  324.  
  325.       return(errno);
  326.     }
  327.  
  328.  
  329.  
  330. 4. Performance Considerations
  331.  
  332.    The TCP/IP device drivers will only accept 16-bit aligned
  333.    pointers.  The sockets DLL deals with this problem by
  334.    allocating temporary memory and copying the corresponding
  335.    data.  To prevent this additional overhead, do not call
  336.    the socket DLL with pointers that cross a 64K boundary.
  337.    For calls that do not send or receive data, this is
  338.    generally not a problem.  It is suggested that the
  339.    programmer allow the sockets DLL to deal with 16-bit
  340.    boundaries in these situations.
  341.  
  342.    For send and receive type calls, the programmer should
  343.    avoid passing pointers that cross 64K boundaries to
  344.    prevent the sockets DLL from copying the data.
  345.  
  346.    For example, to handle this for the send() function:
  347.  
  348.     int SendData(int socket, void *buffer, int len, int flags)
  349.     {
  350.       int rc;
  351.       char *temp    = (char *)buffer;
  352.       int  templen  = len;
  353.       int  errno    = 0;
  354.  
  355.       do {
  356.          /* Never send across a 64K boundary, and  */
  357.          /* never send more than 32K               */
  358.          rc = send(socket, temp, min(min(templen,0xffff-(temp&0xffff)+1), 0x7fff), flags);
  359.  
  360.          if(rc > 0) {
  361.            temp     += rc;
  362.            templen  -= rc;
  363.          } /* endif */
  364.  
  365.       } while (rc > 0) && templen);    /*enddo */
  366.  
  367.       if(templen) {                    /* If there is still data, then  */
  368.         if(rc) errno = -sock_errno();  /*  1. there was an error        */
  369.         else   errno = EPIPE;          /*  2. the connection was closed */
  370.       } /* endif */
  371.  
  372.       return(errno);
  373.     }
  374.  
  375.  
  376.  
  377.  
  378.  
  379.                  *************************************
  380. ***************** UN54155 CORRECTIVE SERVICE DISKETTE *******************
  381.                  *************************************
  382.  
  383.    Topics included in CSD UN54155 are:
  384.  
  385.       1. APAR fixes were the complete content of UN54155.
  386.          For a list of APARS included in the CSD, see the
  387.          Fixed APARs section below.
  388.  
  389.  
  390.  
  391.                  *************************************
  392. *****************            Fixed APARs              *******************
  393.                  *************************************
  394.  
  395. APAR Fixes
  396.  
  397.   The following is a list of APARs fixed in this CSD.
  398.  
  399.   +---------+-------------+-------------------------------+
  400.   | APAR    | MODULES     | DESCRIPTION                   |
  401.   | NUMBER  | AFFECTED    |                               |
  402.   +---------+-------------+-------------------------------+
  403.   | PN47687 | SO32DLL.DLL | Fixed: All calls to SO32DLL   |
  404.   |         | TCP32DLL.DLL| and TCP32DLL are now          |
  405.   |         |             | reentrant.                    |
  406.   +---------+-------------+-------------------------------+
  407.   | PN50502 | FTPAPI.DLL  | Fixed: Proper return code     |
  408.   |         |             | for FTPPUT() with AS/400      |
  409.   |         |             | member files.                 |
  410.   +---------+-------------+-------------------------------+
  411.   | PN50587 | RPC.DLL     | Fixed: General Protection     |
  412.   |         |             | Failure occurs when executing |
  413.   |         |             | SVC GETARGS().                |
  414.   +---------+-------------+-------------------------------+
  415.   | PN51060 | RPCHOUT     | Fixed: RPCGEN generates a     |
  416.   |         |             | syntactically incorrect .H    |
  417.   |         |             | file.                         |
  418.   +---------+-------------+-------------------------------+
  419.  
  420.   The following APAR was fixed in CSD UN54155.  This
  421.   change is included in this CSD as well.
  422.   +---------+-------------+-------------------------------+
  423.   | PN50077 | PRCGEN.EXE  | Fixed:                        |
  424.   |         | SNMP_DPI.H  | IOCTL(SIOCADDRT/SIOCDELRT) did|
  425.   |         | SOCKET.H    | not work when linking to      |
  426.   |         | SO32DLL.LIB | 32-bit dll                    |
  427.   +---------+-------------+-------------------------------+
  428.  
  429.